home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / Interfaces&Libraries / Universal / Interfaces / CIncludes / QD3DExtension.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-17  |  10.1 KB  |  364 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        QD3DExtension.h
  3.  
  4.      Contains:    QuickDraw 3D Plug-in Architecture     Interface File.                                
  5.  
  6.      Version:    Technology:    Quickdraw 3D 1.5.4
  7.                  Release:    Universal Interfaces 3.2
  8.  
  9.      Copyright:    © 1995-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __QD3DEXTENSION__
  18. #define __QD3DEXTENSION__
  19.  
  20. #ifndef __QD3D__
  21. #include <QD3D.h>
  22. #endif
  23. #ifndef __QD3DERRORS__
  24. #include <QD3DErrors.h>
  25. #endif
  26.  
  27.  
  28.  
  29. #if PRAGMA_ONCE
  30. #pragma once
  31. #endif
  32.  
  33. #ifdef __cplusplus
  34. extern "C" {
  35. #endif
  36.  
  37. #if PRAGMA_IMPORT
  38. #pragma import on
  39. #endif
  40.  
  41. #if PRAGMA_STRUCT_ALIGN
  42.     #pragma options align=power
  43. #elif PRAGMA_STRUCT_PACKPUSH
  44.     #pragma pack(push, 2)
  45. #elif PRAGMA_STRUCT_PACK
  46.     #pragma pack(2)
  47. #endif
  48.  
  49. #if PRAGMA_ENUM_ALWAYSINT
  50.     #pragma enumsalwaysint on
  51. #elif PRAGMA_ENUM_OPTIONS
  52.     #pragma option enum=int
  53. #elif PRAGMA_ENUM_PACK
  54.     #if __option(pack_enums)
  55.         #define PRAGMA_ENUM_PACK__QD3DEXTENSION__
  56.     #endif
  57.     #pragma options(!pack_enums)
  58. #endif
  59.  
  60. /******************************************************************************
  61.  **                                                                             **
  62.  **                                Constants                                      **
  63.  **                                                                             **
  64.  *****************************************************************************/
  65. #if TARGET_OS_MAC
  66.  
  67. enum {
  68.     kQ3XExtensionMacCreatorType    = FOUR_CHAR_CODE('Q3XT'),
  69.     kQ3XExtensionMacFileType    = FOUR_CHAR_CODE('shlb')
  70. };
  71.  
  72. #endif  /* TARGET_OS_MAC */
  73.  
  74.  
  75. /******************************************************************************
  76.  **                                                                             **
  77.  **                                    Macros                                      **
  78.  **                                                                             **
  79.  *****************************************************************************/
  80.  
  81. /*
  82.  * Use this Macro to pack the version number for your class.  This would most
  83.  * likely get used in the  kQ3XMethodTypeObjectClassVersion to return the 
  84.  * version for your class.  This method is set up in your meta handler.
  85.  */
  86.  
  87. #define Q3_OBJECT_CLASS_VERSION(major, minor)            \
  88.     (unsigned long) (((major) << 16) | (minor))
  89.  
  90. /*
  91.  * Convenience macros to unpack a version number, accessing the major and the
  92.  * minor version numbers
  93.  */
  94. #define Q3_OBJECT_CLASS_GET_MAJOR_VERSION(version)        \
  95.     (unsigned long) ((version) >> 16)
  96.  
  97. #define Q3_OBJECT_CLASS_GET_MINOR_VERSION(version)        \
  98.     (unsigned long) ((version) & 0x0000ffff)
  99.  
  100.  
  101. /******************************************************************************
  102.  **                                                                             **
  103.  **                                Object Method types                              **
  104.  **                                                                             **
  105.  *****************************************************************************/
  106.  
  107. enum {
  108.     kQ3XMethodTypeObjectClassVersion = FOUR_CHAR_CODE('vrsn')
  109. };
  110.  
  111. typedef unsigned long                     TQ3XObjectClassVersion;
  112.  
  113. enum {
  114.     kQ3XMethodTypeObjectClassRegister = FOUR_CHAR_CODE('rgst')
  115. };
  116.  
  117. typedef CALLBACK_API_C( TQ3Status , TQ3XObjectClassRegisterMethod )(TQ3XObjectClass objectClass, void *classPrivate);
  118.  
  119. enum {
  120.     kQ3XMethodTypeObjectClassReplace = FOUR_CHAR_CODE('rgrp')
  121. };
  122.  
  123. typedef CALLBACK_API_C( void , TQ3XObjectClassReplaceMethod )(TQ3XObjectClass oldObjectClass, void *oldClassPrivate, TQ3XObjectClass newObjectClass, void *newClassPrivate);
  124.  
  125. enum {
  126.     kQ3XMethodTypeObjectClassUnregister = FOUR_CHAR_CODE('unrg')
  127. };
  128.  
  129. typedef CALLBACK_API_C( void , TQ3XObjectClassUnregisterMethod )(TQ3XObjectClass objectClass, void *classPrivate);
  130.  
  131. enum {
  132.     kQ3XMethodTypeObjectNew        = FOUR_CHAR_CODE('newo')
  133. };
  134.  
  135. typedef CALLBACK_API_C( TQ3Status , TQ3XObjectNewMethod )(TQ3Object object, void *privateData, void *parameters);
  136.  
  137. enum {
  138.     kQ3XMethodTypeObjectDelete    = FOUR_CHAR_CODE('dlte')
  139. };
  140.  
  141. typedef CALLBACK_API_C( void , TQ3XObjectDeleteMethod )(TQ3Object object, void *privateData);
  142.  
  143. enum {
  144.     kQ3XMethodTypeObjectDuplicate = FOUR_CHAR_CODE('dupl')
  145. };
  146.  
  147. typedef CALLBACK_API_C( TQ3Status , TQ3XObjectDuplicateMethod )(TQ3Object fromObject, const void *fromPrivateData, TQ3Object toObject, const void *toPrivateData);
  148. typedef CALLBACK_API_C( TQ3Status , TQ3XSharedLibraryRegister )(void );
  149. /******************************************************************************
  150.  **                                                                             **
  151.  **                            Object Hierarchy Registration                      **
  152.  **                                                                             **
  153.  *****************************************************************************/
  154. /*
  155.  *    Q3XObjectHierarchy_RegisterClass
  156.  *    
  157.  *    Register an object class in the QuickDraw 3D hierarchy.
  158.  *    
  159.  *    parentType            - an existing type in the hierarchy, or 0 to subclass
  160.  *                            TQ3Object
  161.  *    objectType            - the new object class type, used in the binary 
  162.  *                        metafile.  This is assigned at run time and returned
  163.  *                          to you.
  164.  *    objectName            - the new object name, used in the text metafile
  165.  *    metaHandler            - a TQ3XMetaHandler (may be NULL for some classes) 
  166.  *                          which returns non-virtual methods
  167.  *    virtualMetaHandler    - a TQ3XMetaHandler (may be NULL as well) which returns
  168.  *                            virtual methods a child would inherit
  169.  *    methodsSize            - the size of the class data needed (see 
  170.  *                            GetClassPrivate calls below)
  171.  *    instanceSize        - the size of the object instance data needed (see 
  172.  *                            GetPrivate calls below)
  173.  */
  174. EXTERN_API_C( TQ3XObjectClass )
  175. Q3XObjectHierarchy_RegisterClass (TQ3ObjectType         parentType,
  176.                                  TQ3ObjectType *        objectType,
  177.                                  char *                    objectName,
  178.                                  TQ3XMetaHandler         metaHandler,
  179.                                  TQ3XMetaHandler         virtualMetaHandler,
  180.                                  unsigned long             methodsSize,
  181.                                  unsigned long             instanceSize);
  182.  
  183. /*
  184.  *    Q3XObjectHierarchy_UnregisterClass
  185.  *    
  186.  *    Returns kQ3Failure if the objectClass still has objects 
  187.  * around; the class remains registered.
  188.  */
  189. EXTERN_API_C( TQ3Status )
  190. Q3XObjectHierarchy_UnregisterClass (TQ3XObjectClass     objectClass);
  191.  
  192. /*
  193.  *    Q3XObjectHierarchy_GetMethod
  194.  *    
  195.  *    For use in TQ3XObjectClassRegisterMethod call
  196.  */
  197. EXTERN_API_C( TQ3XFunctionPointer )
  198. Q3XObjectClass_GetMethod        (TQ3XObjectClass         objectClass,
  199.                                  TQ3XMethodType         methodType);
  200.  
  201. /*
  202.  *    Q3XObjectHierarchy_NewObject
  203.  *    
  204.  *    To create a new object. Parameters is passed into the 
  205.  *    TQ3XObjectNewMethod as the "parameters" parameter.
  206.  */
  207. EXTERN_API_C( TQ3Object )
  208. Q3XObjectHierarchy_NewObject    (TQ3XObjectClass         objectClass,
  209.                                  void *                    parameters);
  210.  
  211. /*
  212.  *    Q3XObjectClass_GetLeafType
  213.  *    
  214.  *    Return the leaf type of a class.
  215.  */
  216. EXTERN_API_C( TQ3ObjectType )
  217. Q3XObjectClass_GetLeafType        (TQ3XObjectClass         objectClass);
  218.  
  219. /*
  220.  *    Q3XObjectClass_GetVersion
  221.  *    This routine obtains the the version of a class, referenced by an
  222.  *    object class type.  Functions for getting the type are in QD3D.h,
  223.  *    if you have the class name.
  224.  */
  225. EXTERN_API_C( TQ3Status )
  226. Q3XObjectHierarchy_GetClassVersion (TQ3ObjectType         objectClassType,
  227.                                  TQ3XObjectClassVersion * version);
  228.  
  229. /*
  230.  *    Q3XObjectClass_GetType 
  231.  *
  232.  *    This can be used to get the type, given a reference 
  233.  *    to a class.  This is most useful in the instance where you register a 
  234.  *    an element/attribute and need to get the type.  When you register an
  235.  *    element, QD3D will take the type you pass in and modify it (to avoid
  236.  *    namespace clashes).  Many object system calls require an object type
  237.  *    so this API call allows you to get the type from the class referernce
  238.  *    that you will ordinarily store when you register the class.
  239.  */
  240. EXTERN_API_C( TQ3Status )
  241. Q3XObjectClass_GetType            (TQ3XObjectClass         objectClass,
  242.                                  TQ3ObjectType *        theType);
  243.  
  244.  
  245. EXTERN_API_C( TQ3XObjectClass )
  246. Q3XObjectHierarchy_FindClassByType (TQ3ObjectType         theType);
  247.  
  248.  
  249.  
  250. /*
  251.  *    Q3XObjectClass_GetPrivate
  252.  *    
  253.  *    Return a pointer to private instance data, a block of instanceSize bytes, 
  254.  *    from the Q3XObjectHierarchy_RegisterClass call.
  255.  *    
  256.  *    If instanceSize was zero, NULL is always returned.
  257.  */
  258. EXTERN_API_C( void *)
  259. Q3XObjectClass_GetPrivate        (TQ3XObjectClass         objectClass,
  260.                                  TQ3Object                 targetObject);
  261.  
  262. /*
  263.  * Return the "TQ3XObjectClass" of an object
  264.  */
  265. EXTERN_API_C( TQ3XObjectClass )
  266. Q3XObject_GetClass                (TQ3Object                 object);
  267.  
  268.  
  269.  
  270. /******************************************************************************
  271.  **                                                                             **
  272.  **                    Shared Library Registration Entry Point                      **
  273.  **                                                                             **
  274.  *****************************************************************************/
  275.  
  276. struct TQ3XSharedLibraryInfo {
  277.     TQ3XSharedLibraryRegister         registerFunction;
  278.     unsigned long                     sharedLibrary;
  279. };
  280. typedef struct TQ3XSharedLibraryInfo    TQ3XSharedLibraryInfo;
  281. EXTERN_API_C( TQ3Status )
  282. Q3XSharedLibrary_Register        (TQ3XSharedLibraryInfo * sharedLibraryInfo);
  283.  
  284. EXTERN_API_C( TQ3Status )
  285. Q3XSharedLibrary_Unregister        (unsigned long             sharedLibrary);
  286.  
  287.  
  288. /******************************************************************************
  289.  **                                                                             **
  290.  **                                Posting Errors                                  **
  291.  **                                                                             **
  292.  **            You may only call these functions from within an extension         **
  293.  **                                                                             **
  294.  *****************************************************************************/
  295. /*
  296.  *    Q3XError_Post
  297.  *    
  298.  *    Post a QuickDraw 3D Error from an extension.
  299.  */
  300. EXTERN_API_C( void )
  301. Q3XError_Post                    (TQ3Error                 error);
  302.  
  303. /*
  304.  *    Q3XWarning_Post
  305.  *    
  306.  *    Post a QuickDraw 3D Warning, from an extension.  Note the warning code you
  307.  *    pass into this routine must already be defined in the table above.
  308.  */
  309. EXTERN_API_C( void )
  310. Q3XWarning_Post                    (TQ3Warning             warning);
  311.  
  312. /*
  313.  *    Q3XNotice_Post
  314.  *    
  315.  *    Post a QuickDraw 3D Notice, from an extension.  Note the notice code you
  316.  *    pass into this routine must already be defined in the table above.
  317.  */
  318. EXTERN_API_C( void )
  319. Q3XNotice_Post                    (TQ3Notice                 notice);
  320.  
  321.  
  322. #if TARGET_OS_MAC
  323. /*
  324.  *    Q3XMacintoshError_Post
  325.  *    
  326.  *    Post the QuickDraw 3D Error, kQ3ErrorMacintoshError, and the Macintosh
  327.  *    OSErr macOSErr. (Retrieved with Q3MacintoshError_Get)
  328.  */
  329. EXTERN_API_C( void )
  330. Q3XMacintoshError_Post            (OSErr                     macOSErr);
  331.  
  332. #endif  /* TARGET_OS_MAC */
  333.  
  334.  
  335.  
  336. #if PRAGMA_ENUM_ALWAYSINT
  337.     #pragma enumsalwaysint reset
  338. #elif PRAGMA_ENUM_OPTIONS
  339.     #pragma option enum=reset
  340. #elif defined(PRAGMA_ENUM_PACK__QD3DEXTENSION__)
  341.     #pragma options(pack_enums)
  342. #endif
  343.  
  344. #if PRAGMA_STRUCT_ALIGN
  345.     #pragma options align=reset
  346. #elif PRAGMA_STRUCT_PACKPUSH
  347.     #pragma pack(pop)
  348. #elif PRAGMA_STRUCT_PACK
  349.     #pragma pack()
  350. #endif
  351.  
  352. #ifdef PRAGMA_IMPORT_OFF
  353. #pragma import off
  354. #elif PRAGMA_IMPORT
  355. #pragma import reset
  356. #endif
  357.  
  358. #ifdef __cplusplus
  359. }
  360. #endif
  361.  
  362. #endif /* __QD3DEXTENSION__ */
  363.  
  364.